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Preface 


The DataLens® Driver for Paradox® Tables lets you access data in Paradox tables 
from within programs that support the DataLens technology such as Lotus® 1-2-3® 
Release 3.1, 

This guide describes the DataLens Driver for Paradox Tables and provides the 
information you need to use it. This guide contains the following sections: 

• Chapter 1 describes the driver and the benefits it provides you. 

• Chapter 2 provides the information you need to know about the DataLens Driver 
for Paradox Tables. You use the information in this chapter together with the 
information provided in the /Data External section in Chapter 2 of the 1-2-3 
Release 3,1 Reference manual to access the data in Paradox tables. 

• Appendix A provides information of particular interest to a network 
administrator, database administrator, or advanced user of the DataLens Driver 
for Paradox Tables. Topics included in this appendix are advanced options, driver 
implementation guidelines, database considerations, and networking and 
communications issues. 


Reading Path 


Your 1-2-3 Release 3.1 Reference manual tells you how to use DataLens drivers with 
1-2-3 to access data in external database tables. To understand the features and 
capabilities of the DataLens Driver for Paradox Tables, read Chapters 1 and 2 in this 
guide. 

If you are a network administrator, database administrator, or advanced user who is 
installing or setting up the DataLens Driver for Paradox Tables for other users, be 
sure to read Appendix A, 


System Requirements 


You must have the following hardware and software to use the DataLens Driver for 
Paradox Tables on your computer: 

• Lotus 1-2-3 Release 3.1. 

• IBM® PC or compatible computer that is capable of running your version of 1-2-3. 

• MS-DOS® version 3.0 or later. 

• 80 KB of random access memory (RAM). These memory requirements are in 
addition to the memory requirements of 1-2-3. 
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• 200 KB disk space, in addition to the disk space requirements of 1-2-3. 

• The DataLens Driver for Paradox Tables can use tables created by Paradox 3,0 and 
can create tables for use by Paradox 3.0. 

You must also know the following information to use the driver: 

• The name of the directory or directories containing the Paradox table or tables you 
want to access. 

• The name of the Paradox table or tables you want to access. 


If You Need Help 


If you need help installing or using the DataLens Driver for Paradox Tables, refer to 
Appendix 2 of the Setting Up manual. This appendix contains the Customer 
Assurance Plan, which provides information about Lotus Customer Support and tells 
you how to replace defective disks or documentation, transfer a software license, and 
upgrade to possible future releases. 


VI 
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Chapter 1 
Introduction 


This chapter introduces DataLens drivers and basic DataLens concepts. 


What is DataLens? 


DataLens is a technology developed by Lotus Development Corporation to help you 
bring the data you need from other sources into your data analysis appUcations, such 
as 1-2-3. The data can be located on a corporate mainframe, a network server, a 
CD-ROM, or a PC. You can also use the DataLens technology to create and update 
data in sources other than 1-2-3. 

DataLens is integrated with 1-2-3, so you do not need to learn new, complicated 
programs and commands. You simply work with famiUar commands and menu 
choices to access the data when you need it and to generate your own database 
queries. 

DataLens gives you this flexibility by using a driver to communicate between 1-2-3 
and the database management system (DBMS) or file system that controls the data 
you want to access. The DataLens driver sends requests from 1-2-3 to the DBMS or 
file system and returns the data to 1-2-3. You need one DataLens driver for each 
DBMS or file system you want to access. 
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Figure 1 -1 Using DataLens drivers 


This guide describes a driver that lets you access data in Paradox tables. You can use 
the DataLens Driver for Paradox Tables with any DataLens-capable appUcation such 
as 1-2-3 Release 3.1 on an IBM or compatible PC running MS-DOS. 
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Benefits of DataLens 


With DataLens, you can access data in Paradox tables from 1-2-3, without learning 
new tools or data query languages. Depending on specific features of the application 
and the driver, you can 

• Create a table 

• Request data from a table 

• Add information to a table 

• Update or delete information already stored in a table 

• Select specific records from a table 

• Perform calculations on information in a table 


Terms and Concepts 


The terms and concepts defined below are used throughout this guide. 

DataLens is a technology that allows applications such as 1-2-3 to access data in 
external data sources. 

An application is a program or package of programs, such as payroll or spreadsheet, 
that performs a task or group of related tasks for a user. A DataLens application is 
an application that can use the DataLens technology to access data outside of the 
application. 1-2-3 Release 3.1 is an example of a DataLens application. 

In this guide, a driver is a program that allows a DataLens application (such as 1-2-3) 
to access data in a specific external data source, for example, Paradox tables. 

In this guide, capabilities refer to the specific DataLens features supported by a 
DataLens application (such as 1-2-3) or a DataLens driver. 

A character set is a group of computer representations of all the characters in a 
specific language, such as English, French, or German. 

A database is a directory, on your local disk or on a server, that contains one or more 
Paradox tables and associated primary indexes, forms, reports, and scripts. 

A database management system (DBMS) is a program that stores and manipulates 
data, for example, Paradox. 

A table is a file that contains a collection of related information in a database, such as 
employee benefit options or quarterly sales information. Each column in a table 
contains one type of information, such as salary or revenue. Each row contains the 
same number and type of items of information. A table is external to a given DBMS or 
application if it is not managed by that DBMS. 
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A record is a group of related columns of information in a table, such as all the 
information about one employee in an employee table or all the sales information for 
a specific branch in a sales table. In a table, a record is a row. 

A field is one category of information in a table, such as employee ID numbers or the 
dollar amoimts of sales in the month of November. In a table, a field is a column that 
contains the same kind of information for each record in the table. 

Data type refers to the classification of values that are stored in a worksheet cell or 
database field. Some common data types are character, integer, floating point, and 
double precision. DataLens transfer types are the data types that DataLens 
recognizes. 

An index is a list of one or more fields used to order and identify the records in a 
table. For example, the employee ID or branch name field might be used to index an 
employee table or a sales table. A primary index is built from all the fields marked as 
index fields. Index fields are marked with an asterisk before the field data type when 
you use 1-2-3 to list the fields in a table. You must also use an asterisk to indicate 
index fields in the table definition that you use to create a new database table. 

In this guide, privileges refer to database access privileges granted to the user, such 
as read-only access or write access. 

A registration system is a method that 1-2-3 uses to determine what drivers and 
what databases are available to 1-2-3 and the user. The DataLens registration system 
uses the registration file (LOTUS.BCF) to store this information. 

Database administrator refers to the individual or department responsible for 
managing the databases and for granting user access privileges. 

Network administrator refers to the individual or department responsible for 
managing the communications link between the user's computer and the computer 
where the data is located. 
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Chapter 2 

What this Driver Provides 


This chapter contains information you need to know about the DataLens Driver for 
Paradox Tables. It describes the driver's features, benefits, and capabilities, and 
describes driver performance considerations. 

/Data External in Chapter 2 of the 1-2-3 Release 3.1 Reference manual describes how 
to use DataLens drivers with 1-2-3 to access data in external database tables. Use the 
information in this chapter with your 1-2-3 documentation to make the most of your 
data access capabilities. Additional information for advanced users and network 
administrators is included in Appendix A of this guide. 


Driver Overview 


The DataLens Driver for Paradox Tables lets you access information in Paradox 
tables from within 1-2-3 Release 3.1. You can retrieve data from existing Paradox 
tables; add, delete, or modify data from existing Paradox tables; delete Paradox 
tables and associated files; create new Paradox tables; select specific records from a 
table; and perform calculations on information in a table. 

The DataLens Driver for Paradox Tables works directly with Paradox tables. It does 
not use the Paradox program to access the tables. This means that you do not need to 
have Paradox up and running to use the DataLens Driver for Paradox Tables. 

The DataLens Driver for Paradox Tables can create and use any Paradox table, except 
those that are password protected. If a table is write protected, you can retrieve 
information from the table, but you cannot add to, delete from, update, or modify the 
table. You can use the DataLens Driver for Paradox Tables to create and access tables 
with primary indexes. 


Capabilities and Options 


This section describes the driver's capabilities and the data types, character sets, and 
database commands it supports. 

Capabilities 

In general, the DataLens Driver for Paradox Tables relies on the functionality of the 
DataLens application. Since 1-2-3 provides record selection, data query, and 
calculation functions, for example, the DataLens Driver for Paradox Tables passes the 
entire Paradox table to 1-2-3, which then performs the functions you request. You can 
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use l-2“3 /Data Query commands and 1-2-3 @fimctions on Paradox tables simply by 
specifying the range name you assigned to the Paradox table as the input range. 

All DataLens drivers are capable of sequentially reading the rows in a table. The 
following list describes the additional general capabilities of the DataLens Driver for 
Paradox Tables: 

• Modify table definition and structure (create and delete tables) 

• Modify rows of a table (insert, update, and delete rows) 

Supported Data Types 

Because different DBMS and file systems use different types of data, DataLens must 
convert the various data types into a common format so you can use the data in 1-2-3 
and add or update data in the database tables. This data type conversion is handled 
automatically by 1-2-3 and the DataLens Driver for Paradox Tables. 

Occasionally you may want more information about how specific data types are 
converted. Table 2-1 shows the 1-2-3 data types that each Paradox data type may be 
converted to. 

Table 2-1 Converting Paradox data types to 1-2-3 data types 


Table creation 1-2-3 data 

Paradox data type^ type^ Description type 


[*]Alphanumerlc (A) 

[*]Character 

Strings containing letters, 
numbers, and special 
characters 

Label 

HNumber (N) 

[*]Number 

Floating point numbers 

Value 

[*]Currency ($) 

nCurrency 

Number fields with a default 
currency display format 

Value 

HDate (D) 

□Date 

Date values, for example, 
06/21/90, 29-JUI-89, or 
19.01.96 

Date/Time 

nShort (S) 

nShort 

Integers 

Value 


1 - An optional asterisk next to the data type indicates that the field is a primary index field. 

2 - Use this data type name in the table definition when you create a table. 


Supported Character Sets 

The DataLens Driver for Paradox Tables supports the Paradox character set, which is 
U.S. ASCII code page 437. 
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Paradox Sort Orders 

Paradox uses alternative sort orders to allow users to sort records in indexed tables 
based on their native language. The DataLens Driver for Paradox Tables supports the 
Paradox sort orders ASCII, Inti (International), SwedFin (Swedish/Finnish), and 
NorDan (Norwegian/Danish) for indexed tables. The DataLens Driver for Paradox 
Tables maintains the index in the sort order that was used when the table was 
created. When creating a new indexed Paradox table, the driver uses the ASCII sort 
order unless you specify a different sort order in the table creation string. Valid table 
creation strings are shown in the following table. Refer to the /Data External Other 
Command section in Chapter 2 of the 1-2-3 Release 3.1 Reference manual for more 
information about specifying table creation strings. 

Table 2-2 Table creation strings for Paradox tables 

Table creation string Description 

SORT ASCII ASCII sorting order 

SORT INTL International ASCII sorting order 

SORT NORDAN Norwegian/Danish sorting order 

SORT SWEDFIN Swedish/Finnish sorting order 


Driver-Supported Paradox Commands 

The DataLens Driver for Paradox Tables does not use the Paradox program to access 
the tables. Therefore, you cannot execute Paradox commands from 1-2-3. 


Creating Paradox Tables 


When you use a DataLens driver to create a new database table, you must first create 
a table definition following the instructions in the /Data External Create section in 
Chapter 2 of the 1-2-3 Release 3.1 Reference manual. The table definition contains six 
columns of information: the names of the fields you want to create, the data type for 
each field, the field widths, field labels, field descriptions, and field creation strings. 
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Figure 2-1 illustrates a table definition. Note that the column headings in this 
illustration are not part of the definition; they are added for clarity. 
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Field 

Field 

Field 

Creation 

Field Name 

Data Type 

Width 

Label 

Description 

String 

EMPiD 

‘Number 





LASTNAME 

Character 

12 




FIRSTNAME 

Character 

12 




DOH 

Date 





SALARIED 

Character 

1 




DEPTNUM 

Number 






Figure 2-1 Sample table definition 

If you use the DataLens Driver for Paradox Tables to create new Paradox table files, 

keep these rules in mind: 

• Field names must be unique; uppercase and lowercase versions of the same 
character are not unique. For example, "NAME" and "Name" are not unique field 
names. 

• Field names can be a maximum of 25 characters long. 

• Valid data types are Character, Date, Number, Currency, and Short. See 
"Supported Data Types" earlier in this chapter for more information. 

• To create an indexed table, precede the data type of the index fields with an 
asterisk, for example, ^Number. 

• To create an indexed table, list all the index fields first, in order of precedence. All 
of the index fields must appear before any non-index fields. Note that all of the 
index fields combined comprise the primary index for the table. 

• The field width indicates the maximum width of a character field. Do not specify 
a field width for non-character fields. 1-2-3 will return an error if a field width is 
specified for non-character fields. 

• The DataLens Driver for Paradox Tables requires that you specify the field name 
and data type for all fields, and the field width for character fields. The driver 
ignores the field label, field description, and field creation string fields of the table 
definition. 
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Adding and Updating Records 


Before you begin modifying an existing Paradox table, use your operating system 
commands to make a backup copy of the table file (.DB). If the table is indexed, you 
should also make a backup copy of the index file (.PX). Then, if you receive an error 
message while you are adding or updating records, and the table is only partially 
updated, you can correct the cause of the error, copy the backup file, and restart your 
insert or update procedure. 

The DataLens Driver for Paradox Tables does not modify primary index fields or 
insert records whose index is identical to an existing index. To achieve the same 
results, you can delete the existing record and insert the new, modified record. The 
index file (.PX) must be located in the same directory as the table file (.DB). 
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Appendix A 
Administration 


This appendix describes issues of particular interest to a network administrator, 
database administrator, or advanced user. Topics include modifying the registration 
file and database considerations. 


Modifying the Registration File 


The registration file (LOTUS.BCF) contains information about DataLens drivers and 
databases you want to make available to your users. DataLens applications, such as 
1-2-3, use the information in the registration file to connect to drivers and databases. 

The registration file consists of driver records and database records. Driver records 
tell 1-2-3 which drivers to list for users to select from and which parameters and 
configuration options to use with those drivers. Database records allow you to tell 
1-2-3 which databases to list for users to select from. Database records are not 
required. 

Driver Record Parameters 

When 1-2-3 installs the DataLens Driver for Paradox Tables, the registration file 
contains a driver record to give users access to the driver. The driver record will look 
similar to this: 

DN-'TaraLens^' DL='TaraLens" 

DD="DataLens Driver for Paradox Tables" 

DC="C:\123R3"; 

The database administrator may want to change the parameters or options in a 
driver record in order to customize the driver for users. 
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The registration file must contain at least one driver record. A driver record can have 
several parts (parameters). When creating or editing a driver record for the DataLens 
Driver for Paradox Tables, you can use the following parameters, three of which are 
required with this driver: 


Table A-1 Driver record parameters 


Parameter 

Required 

Example 

Description 

DN=“Dr/Vemame” 

Yes 

DN=“ParaLens” 

DN identifies the record as a 
driver record and must be the 
first parameter in the record. 
Drivername is the name 1 -2-3 
will display to the user. The 
driver name cannot include 
spaces and must be enclosed in 
“ ” (quotation marks). This name 
must be unique for each driver 
record. 

DriverFilenam^' 

Yes 

DL=“ParaLens” 

DL specifies the file name 
(without the extension) of the 
driver program (ParaLens for 
the DataLens Driver for Paradox 
Tables). Enclose the name in “ ” 
(quotation marks). 

DD=“Dr/Ver 

Description" 

No 

DD=“DataLens 
Driver for 

Paradox 

Tables” 

DD specifies a description of the 
driver. 1-2-3 displays this 
description to the user when the 
user is selecting a driver. 

Enclose the description In “ ” 
(quotation marks). 

DC=‘Driver 

Configuration 

Informatiorf’ 

Yes 

DC=“C:\123R3” 

DC sends configuration 
information to the driver. 

Enclose the configuration 
information in “ ” (quotation 
marks). For the DataLens Driver 
for Paradox Tables, this 
parameter lists the path of your 
1-2-3 Release 3.1 program 
directory. The driver files must 
be in the 1-2-3 program 
directory. 
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Driver and Database Record Syntax 

This section describes the syntax rules for records in the registration file. Follow these 
rules when adding or editing records in the registration file. 

Parameter syntax 

• Use = (equal sign) to separate the parameter name from the value of the 
parameter, such as DN="ParaLens", Do not include a space before or after the 
equal sign. 

• When using the DN, DL, DC, and DD parameters, enclose the value of the 
parameter in " " (quotation marks), such as DL="ParaLens". 

Record syntax 

• Include at least one space between parameters in a record. 

• Include a ; (semicolon) after the last parameter in a record. 1-2-3 interprets all 
parameters as being part of one record until it encounters a; (semicolon). A record 
can wrap to several lines. 

• Driver and database records can be in any order in the registration file. 

Database Record Parameters 

Database records are optional. You can add and delete database (directory) entries in 
the DataLens registration file (LOTUS.BCF). If a database is listed in the registration 
file, a user can select that database name from the list that 1-2-3 displays. If a 
database is not listed in the registration file, 1-2-3 cannot display the database name, 
but a user can still type any valid database name to select a database. 
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When creating or editing a database record, you can use the following parameters, 
two of which are required: 


Table A-2 Database record parameters 


Parameter 

Required 

Example 

Description 

DB='Databasename'' 

Yes 

DB=“C:\STAFF” 

DB identifies the record as a 
database record and must be 
the first parameter in the 
record. Databasename is the 
database (directory path) 
name. 1-2-3 displays this path 
to the user. Do not Include 
spaces in the database name. 
Enclose the name in “ ” 
(quotation marks). 

DN=“Dr/Vername” 

Yes 

DN=“ParaLens” 

DN specifies the name of the 
driver as you specified it in the 
DN parameter of the driver 
record. In a database record, 
the DN parameter must follow 
the DB parameter. Enclose the 
name in “ ” (quotation marks). 

If the driver name in this record 
does not match the driver 
name in any driver record in 
the file, 1-2-3 ignores this 
database record. 

DD= “Database 
Description" 

No 

DD=“Employees 
throughout the 
world” 

DD specifies a description of 
the database. 1-2-3 may 
display this description to 
users. Enclose the description 
in “ ” (quotation marks). 


An example database record is 

DB=''C:\STAFF" DN='TaraLens" 

DD=''Employees throughout the world"; 

Sequence of Records in the Registration File 

The driver and database records in the registration file are not required to be in any 
specific sequence. However, the sequence of the records does affect the order in 
which drivers and databases are listed for the user. The driver named in the first 
driver record in the registration file is the first driver displayed when the user wants 
to use a driver. Likewise, the first database record names the first database 
(directory) that is displayed to the user. You can rearrange the sequence of records in 
the registration file to suit your needs. 
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standard Registration Files 

The sequence of the records in the registration file determines the order in which 
drivers and databases are listed for the user. To maintain a consistent user interface 
and support shared macros, create and distribute one registration file for all users or 
each group of users. 

NOTE The registration file lists the directory that contains the driver files. If this 
directory is not the same for all users, you or the users can edit the DC parameter of 
the driver record in the LOTUS.BCF file. 


Database Considerations 


The following sections describe how the driver works with the DBMS, and identify 
database factors that can affect data integrity, driver performance, and ease of use. 

DBMS and Driver Communication 

The DataLens Driver for Paradox Tables works directly with Paradox tables. It does 
not use the Paradox program to access the tables, which means that users do not 
need to have Paradox up and running. 

The use of the DataLens Driver for Paradox Tables for anything other than 
single-user access of Paradox tables is not recommended. The driver supports 
read-only access on shared drives and is not intended for concurrent access of tables 
with either other driver users or other Paradox users. 

When a user deletes a table, the DataLens Driver for Paradox Tables also deletes the 
primary index file (.PX), if it exists. The driver does not delete other files — forms, 
reports, and scripts — in the table's family. 

Security and Privileges 

Users cannot create or use password-protected Paradox tables from the DataLens 
Driver for Paradox Tables. If a Paradox table is write protected, users can read the 
data in the table using the DataLens Driver for Paradox Tables, but cannot write to 
the table, delete records in the table, or delete the table. 

To prevent users of the DataLens Driver for Paradox Tables from reading a Paradox 
table, use any level of Paradox password protection. 

To prevent users from modifying or deleting a Paradox table, write protect the table 
from within Paradox, 

You can also use standard operating system or network security mechanisms to 
control user access to Paradox tables. 
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Removing the Driver 

To remove the DataLens Driver for Paradox Tables from your hard disk, erase the 
following files from your 1-2-3 Release 3.1 program directory: 


File 

Description 

PARALENS.DLD 

Driver program file 

PARALENS.DL2 

Driver program file 

PARALENS.INI 

Driver configuration file 

PARALENS.RI 

Driver message file 


You or your database administrator or network administrator can delete the driver 
and database entries from your LOTUS.BCF file so 1-2-3 does not display them. 
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